ZATCA ERPgulf Event Log – API Response Handling

The ZATCA ERPgulf Event Log Doctype is designed to manage and track all ZATCA API submissions for Sales Invoices, Credit Notes, and Debit Notes. It supports Standard, Simplified, Credit Note, and Debit Note types and records submissions across background jobs, batches, and live API calls. The Doctype captures response status, titles, API messages, and submission timestamps for auditing, monitoring, and troubleshooting purposes.

Update Summary

Added centralized logging for all ZATCA API responses.
Logs track invoice number, response message, status label, UUID, and submission time.
Supports handling of Success, Warning, Duplicate, and Failure responses.

Response Handling Logic

When a ZATCA API response is received:

Success (HTTP 200)

status_label = "Success"
title = f"ZATCA Success - {invoice_number}"

Warning (HTTP 202)

status_label = "Warning"
title = f"ZATCA Invoice with Warnings - {invoice_number}"

Duplicate Invoice (HTTP 409)

status_label = "Success (Duplicate Invoice)"
title = f"ZATCA Duplicate Success - {invoice_number}"

Other Failures (Any other HTTP code)

status_label = f"Failed (HTTP {response.status_code})"
title = f"ZATCA API Failed - {invoice_number}"

Log Message Content

The log stores the status code and the full API response from ZATCA for auditing and troubleshooting purposes. For example, it records the status code along with the response text received from the API.

Event Log Creation

Each API submission creates a new event log entry that records the following:

Title summarizing the event, e.g., “ZATCA Success – INV-0001” or “ZATCA API Failed – INV-0001”.
Invoice Number associated with the submission.
Response Text, including the status code and API response.
UUID for tracking the submission uniquely.

Usage Scenarios

Live Submission: Logs created for real-time API calls.
Batch Submission: Logs created for multiple invoices processed in a batch.
Background Jobs:Logs generated by background worker processes submitting invoices.

Benefits

Centralized tracking of all ZATCA API submissions.
Clear status labels for easy monitoring and troubleshooting.
Stores full API response for auditing or debugging.
Supports multiple document types and submission modes.
Provides time-stamped logs for compliance and reporting.